---
title: Webhooks
---

Webhooks are user-defined HTTP callbacks. They are triggered by events in Configu and allow integration with different applications or third-party APIs. Webhooks in Configu are commonly used for sending messages or integrating with CI/CD platforms.
For example, a webhook can trigger a Github action flow when a Config is changed or notify about it in a Slack channel.

## Creating a Webhook

1. Go to the **Webhooks** page under the **Integrations** tab
2. Click the **Create Webhook** button and provide the webhook name and URL (both are mandatory fields)
3. After adding the webhook, you will see it listed in the Webhooks list

<Frame>![image](/images-old/webhooks/create-webhook.gif)</Frame>

## Customizing Webhooks

### Customizing webhook events

The webhooks feature supports the ability to define which actions ("events") within the organization trigger the webhook invocation.
You may set the webhook to be triggered by all events or select individual events that are relevant to the use case of your webhook from the following list:

- `Upsert configs` - Upsert of config values to any and all sets.
- `Eval configs` - Evaluation or exports of config values from any and all sets.

### Customizing webhook payloads

You may use any of the predefined webhook payload properties within the header context by using [mustache templating](https://mustache.github.io/) as such:

<Frame>![image](/images-old/webhooks/webhook-payload.png)</Frame>

List of generic properties:

- `orgId` - The unique identifier of your organization
- `message` - A simple string message that changes depending on the event that triggered the invocation
- `appUrl` - Link to the organization page within the Configu Cloud
- `assignee` - An object containing data regarding the entity that triggered the webhook
  - `assignee.type` - The value can be `token` or `user` depending on the credentials used to trigger the webhook
  - `assignee.name` - The name of the assignee which is either the token name or the user name
- `webhook` - An object containing the metadata of the webhook that was triggered
  - `webhook.contentType` - The content type of the webhook
  - `webhook.events` - An array that events that trigger the webhook
  - `webhook.isActive` - Indicates if the webhook is enabled or disabled
  - `webhook.name` - The display name of the webhook
  - `webhook.orgId` - The organization identifier of the webhook-owning organization
  - `webhook.createdAt` - A timestamp of the creation time of the webhook
  - `webhook.updatedAt` -A timestamp of the last update time of the webhook
  - `webhook.url` - The URL that receives an HTTP request when the webhook is invoked
- `event.type` - The type of the event from the list defined above
- `event.timestamp` - A timestamp of the time that the event was triggered
- `event.payload` - An object containing properties that change based on the event type

### Upsert configs event payload data

- `event.payload.upsertedConfigs` - An array containing all the configs that were upserted
- `event.payload.stagedSets` - An array containing all the unique sets that had at least one config that changed its value
- `event.payload.stagedConfigs` - An array containing all the configs that had their value changed as a result of the upsert

### Eval configs event payload data

- `event.payload.queries` - An array containing all the evaluation queries that were made to the Configu store.

### Customizing webhook headers

Webhook headers and payloads may be customized for specific use cases where you need to add properties to the webhook invocation.

By default, Configu sets the following headers:

- `content-type` - The value is defined by the content type you select when defining the webhook. The value cannot be changed by customizing the headers to ensure consistency.
- `user-agent` - Always set to `@configu/ua`. This value cannot be changed to ensure that you can consistently identify webhook invocations originating from Configu.

Popular examples of headers that you might want to customize:

- `authorization` - In cases where you need to authenticate the invocation you may set the authorization header to contain the required credentials.

### Additional notes

- When customizing both the webhook headers and payload, you may use any of the keywords mentioned above.
- Customizing the webhook payload overrides the default payload properties
- Using a keyword that is not defined within the context of the webhook will result in an empty value
- The value of the keyword is always stringified
- `event.payload` is an object, use [mustache templating](https://mustache.github.io/) syntax to extract your desired data.
  for example: to print upserted configs use: `{{#event.payload.upsertedConfigs}}{{key}}{{value}}`

## Verify Webhook with test request

To verify that the webhook works, press on the **Test Webhook** button under the three dots menu.

<Frame>![image](/images-old/webhooks/webhook-test.png)</Frame>

## Disabling or Removing a Webhook

Enable or disable a webhook by clicking the Status button.
A webhook can be removed by clicking the Remove button under the dots menu.

## Integrations you might be interested in

- Communication
  - [Discord](/guides/platform/discord-webhook)
  - [Slack](/guides/platform/slack-webhook)
  - Microsoft teams
  - Telegram
  - HubSpot
  - Twilio
  - Gmail
- CI/CD Trigger
  - [Github Action](/guides/platform/github-actions-webhook)
  - GitLab CI/CD
  - Circle CI
- Others
  - Zapier - allows integrations with hundreds of applications. See the full list on the [Zapier website](https://zapier.com/apps).
